The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props justlevine, westonruter.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• The Plugin and Theme Directories cannot be accessed within Playground.
• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

In Gruntfile.js, there is a precommit task, which includes precommit:php as well as format:php. Curiously, it doesn't to lint:php (probably because there are still so many violations), but it should run PHPStan since it can run on the entire codebase without errors.

I tried running composer analyse and it seemed to finish but then it hung at 99%. Finally it errored:

I tried running composer analyse and it seemed to finish but then it hung at 99%. Finally it errored:

@westonruter can you run it with -- --vvv? I believe that should show us which file it's timing out on.

(Also confirming that you're using the vanilla phpstan.neon.dist and the CLI is just inaccurate - if not, please share any modifications there too)

Actually, I was using a local phpstan.neon which was overriding the one provided in this PR. When I try using the one in the PR, the result is actually worse. It never starts analyzing. This seems to be due to the paths config:

If I change it to:

	paths:
		- ../../src/wp-admin
		- ../../src/wp-includes

Then it works, aside from two errors being found:

 ------ ---------------------------------------------------------------------- 
  Line   wp-admin/load-scripts.php                                             
 ------ ---------------------------------------------------------------------- 
  68     Function get_file not found.                                          
         🪪  function.notFound                                                 
         💡  Learn more at https://phpstan.org/user-guide/discovering-symbols  
         at src/wp-admin/load-scripts.php:68                                   
 ------ ---------------------------------------------------------------------- 

 ------ ---------------------------------------------------------------------- 
  Line   wp-admin/load-styles.php                                              
 ------ ---------------------------------------------------------------------- 
  83     Function get_file not found.                                          
         🪪  function.notFound                                                 
         💡  Learn more at https://phpstan.org/user-guide/discovering-symbols  
         at src/wp-admin/load-styles.php:83                                    
 ------ ---------------------------------------------------------------------- 

What appears to be the issue is that I use my wordpress-develop clone for core and plugin development together. So my src/wp-content is very large. I know other contributors do this as well, so this is something which should be accounted for.

Nevertheless, the change I made is not ideal because then it doesn't check the PHP files in the root of src, like wp-login.php. I'm confused because from looking at the excludePaths config, it would seem that src/wp-content is supposed to be excluded, and yet PHPStan still seems to be scanning all the 16GB worth of files in the plugins dir.

Gemini's review

This is a comprehensive review of the changes proposed for integrating PHPStan into WordPress core. The review focuses on technical accuracy, adherence to WordPress coding standards, PHP 7.4 compatibility, and overall architectural consistency.

GitHub Workflows

• .github/workflows/php-static-analysis.yml:
  • Logic: The on triggers correctly include trunk and stable branches ([7-9].[0-9]).
  • Nit: The concurrency group naming is consistent with other core workflows.
• .github/workflows/reusable-php-static-analysis.yml:
  • Build Dependency: It correctly runs npm run build:dev before analysis. This is crucial because many core PHP files are generated or modified during the build process, and PHPStan needs the final state of the files.
  • Caching: The use of a weekly-rotated custom cache suffix (based on "last Monday") is a smart way to manage the composer update environment without a lockfile.
  • Missing @ticket: As this is a new file in the .github directory (part of the CI/CD "tests" infra), it would ideally mention the Trac ticket in a comment at the top, though it's not strictly required by core standards for YAML.

General Configuration

• .gitignore: Added /phpstan.neon. This is correct to allow developers to create local overrides of the .dist file.
• composer.json:
  • Nit: The phpstan script uses @php. This is good for cross-platform compatibility.
  • Dependency: phpstan/phpstan: ~2.1.33 is appropriate.
• phpstan.neon.dist:
  • Level 0: A sensible starting point for a codebase of this size.
  • Inner Functions: The ignoreErrors for inner functions in wp-admin/includes/export.php etc., are necessary because PHPStan does not support them. This is a known architectural quirk of WordPress core.
• tests/phpstan/base.neon:
  • Performance Fix: The change from a blanket ../../src path to explicit paths for wp-admin, wp-includes, and root PHP files is a vital fix for the "hanging" issue caused by wp-content traversal.
  • Missing Themes: While listing themes explicitly is a good workaround for the hang, it means any new default theme added to core will need to be manually added here. A comment should be added to remind future developers of this.
• tests/phpstan/bootstrap.php:
  • Standards: This file uses tabs for indentation and follows core's define style.
  • Missing @ticket: This file should have a @ticket tag in its header docblock.

Core PHP Changes

• src/wp-includes/functions.php (wp_die):
  • Type Hint: @phpstan-return ($args['exit'] is false ? void : never) is an excellent use of conditional types to accurately represent the behavior of wp_die().
• src/wp-includes/class-wp-theme.php:
  • Conditional Type: The @phpstan-return for get() is technically correct but very complex.
  • Nit: It returns mixed for unknown headers. Given that the underlying headers property is array<string, string>, and sanitize_header returns string|array, it might be safer to narrow mixed to string|array|false.
• src/wp-includes/html-api/class-wp-html-processor.php:
  • Return Never: Adding @return never to bail() is the correct fix for the "missing return statement" errors in calling methods.
• src/wp-includes/customize/class-wp-customize-filter-setting.php:
  • Logic Change: You added return true; to an empty update() method. While this satisfies PHPStan's requirement for a bool return, ensure this doesn't conflict with any child classes that might expect a void return (though in this case, the base class defines it as returning true|WP_Error usually).

Theme Changes

• src/wp-content/themes/twentytwentyone/classes/class-twenty-twenty-one-customize.php:
  • Bug Fix: The addition of the if ( $setting ) check is a genuine bug fix discovered by PHPStan. Previously, it would have caused a fatal error if blogname or blogdescription were missing (unlikely, but possible in some environments).
• src/wp-content/themes/twentytwentyone/classes/class-twenty-twenty-one-svg-icons.php:
  • Cast: (string) preg_replace(...). Since preg_replace can return null on error (or an array if the input was an array), the cast ensures compatibility with the string return type of get_svg(). This is safe here as the input is a known string.

Documentation

• tests/phpstan/README.md:
  • Accuracy: The paths have been corrected to src/wp-includes/....
  • Style: Uses US spelling ("analyze") consistently with the rest of the PR.

Summary of Nit-picks & Concerns:

1. Indentation: Ensure tests/phpstan/base.neon and phpstan.neon.dist use tabs for indentation within the YAML/NEON structures where appropriate (though NEON usually accepts spaces, tabs are core's preference). Self-correction: Looking at the diff, it seems tabs are used.
2. @since vs @ticket:
   • tests/phpstan/base.neon: New file. Should have a Trac ticket reference in a comment.
   • tests/phpstan/bootstrap.php: New file. Needs @ticket.
   • tests/phpstan/README.md: New file. No @since needed (it's a test asset), but Trac ticket reference is good practice.
3. PHP 7.4 Compatibility: All changes use syntax compatible with PHP 7.4. The use of @phpstan-ignore for GdImage in media.php is the correct way to handle class existence that depends on the PHP version.
4. WP_Theme::get(): The return type mixed at the end of the conditional might be too broad. Since the method is intended to return string|array|false, it would be better to use that instead of mixed.

Overall, this is a very high-quality integration that significantly improves the type safety of WordPress core without introducing unnecessary noise or performance regressions.

Overall, this is a very high-quality integration that significantly improves the type safety of WordPress core without introducing unnecessary noise or performance regressions.

Thank you robot overlord 🦾🦾🦾

• Missing @ticket: As this is a new file in the .github directory (part of the CI/CD "tests" infra), it would ideally mention the Trac ticket in a comment at the top, though it's not strictly required by core standards for YAML.

• tests/phpstan/bootstrap.php:

  • Missing @ticket: This file should have a @ticket tag in its header docblock.

Is this a real concern?

• Missing Themes: While listing themes explicitly is a good workaround for the hang, it means any new default theme added to core will need to be manually added here. A comment should be added to remind future developers of this.

This seems like a nonproblem themes are added to core manually anyway...

• src/wp-includes/class-wp-theme.php:

  • Conditional Type: The @phpstan-return for get() is technically correct but very complex.
  • Nit: It returns mixed for unknown headers. Given that the underlying headers property is array<string, string>, and sanitize_header returns string|array, it might be safer to narrow mixed to string|array|false.

• src/wp-includes/html-api/class-wp-html-processor.php:

I need to check this from a computer 📝

• Logic Change: You added return true; to an empty update() method. While this satisfies PHPStan's requirement for a bool return, ensure this doesn't conflict with any child classes that might expect a void return (though in this case, the base class defines it as returning true|WP_Error usually).

There's an open thread on this already...

Theme Changes

• src/wp-content/themes/twentytwentyone/classes/class-twenty-twenty-one-customize.php:

  • Bug Fix: The addition of the if ( $setting ) check is a genuine bug fix discovered by PHPStan. Previously, it would have caused a fatal error if blogname or blogdescription were missing (unlikely, but possible in some environments).

• src/wp-content/themes/twentytwentyone/classes/class-twenty-twenty-one-svg-icons.php:

  • Cast: (string) preg_replace(...). Since preg_replace can return null on error (or an array if the input was an array), the cast ensures compatibility with the string return type of get_svg(). This is safe here as the input is a known string.

I don't remember introducing these changes, I have no indication whether this is legitimate or a hallucination.

{the next bunch of lines seemed like it was agreeing with me, thank you 🤖that's why I did it that way...}

PS:

I feel like the above contribution was "workslop". You didn't use AI to make your job as a reviewer easier, you gave me some pointless busywork: a bunch of autogenerated text that I then had to sift through to try and derive meaning or see if there was any value there. Even the few points where it could have been helpful, aren't IRL because I don't know whether you @westonruter, trusted reviewer and committer, vetted the details, or if it's all just probabilistic garbage puked out by a mid-tier model (I don't even know which model was used, what harness...)

IMO a "good" use of AI here would have been

1. You review the results of your own prompt, and evaluate the results yourself.

2. If your model flagged something and you agree with the assessment - then I don't even care that you used AI and wouldn't noticed if you didnt disclose.

3. If your model flagged something, and you weren't sure of the results, then that's a good opportunity to share and disclose. E.g:

   Hey, I prompted Gemini (CLI with 3.0-auto ), and it flagged {e.g. such and such concern about adding a ticket number to any new file headers }. I think that make sense but don't feel too strongly about it.

4. I'm hesitant to recommend the value in disclosure if the model approves of a pr. That's also not an actionable quality signal - at least not from current gen models.

Tl;dr proposing the principle of "you own your ai":

It's only "helpful" to disclose your LLM usage as a quality signal regarding the level of intentionality in the "work product" (code, code review, human opinion, etc)

Everything else is slop.

If you contribute it, you "own" it, and if you can't own it yourself, then disclaim it so other folks know the level of signal to give it.

I cited Gemini's review clearly labeled as Gemini's so we could take it as face value. Bottom line is it didn't find any red flags. I used it as a sanity check and I included it here for transparency.

I don't remember introducing these changes, I have no indication whether this is legitimate or a hallucination.

I made these changes, referenced in #10419 (comment)

@justlevine I also got to the bottom of the issue with wp_insert_user() causing PHPStan to hang. Or at least, I think I did. The issue is that PHPStan couldn't figure out what $userdata's type was. So in 77d9403...512e368 I've ensured that $userdata always is a string, and I went the extra mile to ensure back-compat for passing in unexpected values to that function.

As part of that, it is also now analyzing the core themes. I fixed the issues it newly identified.

• I've cherry-picked these changes into a separate PR for review: Fix PHPStan level 0 issues in themes #10951

• PR for Customizer PHPStan fixes: Fix PHPStan level 0 issues for Customizer setting subclasses by returning correct types #10952

• PR for fix to user.php: Fix PHPStan error with wp_insert_user() which causes it to hang #10953